<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>Tcl_SaveResult manual page - Tcl Library Procedures</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl C API</a> <small>&gt;</small> SaveResult</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="SaveResult.htm#M2" NAME="L680">NAME</A>
<DL><DD>Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult &mdash; save and restore an interpreter's state</DD></DL>
<DD><A HREF="SaveResult.htm#M3" NAME="L681">SYNOPSIS</A>
<DL>
<DD><B>#include &lt;tcl.h&gt;</B>
<DD>Tcl_InterpState
<DD><B>Tcl_SaveInterpState</B>(<I>interp, status</I>)
<DD>int
<DD><B>Tcl_RestoreInterpState</B>(<I>interp, state</I>)
<DD><B>Tcl_DiscardInterpState</B>(<I>state</I>)
<DD><B>Tcl_SaveResult</B>(<I>interp, savedPtr</I>)
<DD><B>Tcl_RestoreResult</B>(<I>interp, savedPtr</I>)
<DD><B>Tcl_DiscardResult</B>(<I>savedPtr</I>)
</DL>
<DD><A HREF="SaveResult.htm#M4" NAME="L682">ARGUMENTS</A>
<DL class="arguments">
</DL>
<DD><A HREF="SaveResult.htm#M5" NAME="L683">DESCRIPTION</A>
<DD><A HREF="SaveResult.htm#M6" NAME="L684">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult &mdash; save and restore an interpreter's state
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;tcl.h&gt;</B><BR>
Tcl_InterpState<BR>
<B>Tcl_SaveInterpState</B>(<I>interp, status</I>)<BR>
int<BR>
<B>Tcl_RestoreInterpState</B>(<I>interp, state</I>)<BR>
<B>Tcl_DiscardInterpState</B>(<I>state</I>)<BR>
<B>Tcl_SaveResult</B>(<I>interp, savedPtr</I>)<BR>
<B>Tcl_RestoreResult</B>(<I>interp, savedPtr</I>)<BR>
<B>Tcl_DiscardResult</B>(<I>savedPtr</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*interp</B> (in)<DD>
Interpreter for which state should be saved.
<P><DT>int <B>status</B> (in)<DD>
Return code value to save as part of interpreter state.
<P><DT>Tcl_InterpState <B>state</B> (in)<DD>
Saved state token to be restored or discarded.
<P><DT>Tcl_SavedResult <B>*savedPtr</B> (in)<DD>
Pointer to location where interpreter result should be saved or restored.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
These routines allows a C procedure to take a snapshot of the current
state of an interpreter so that it can be restored after a call
to <B><A HREF="../TclLib/Eval.htm">Tcl_Eval</A></B> or some other routine that modifies the interpreter
state.  There are two triplets of routines meant to work together.
<P>
The first triplet stores the snapshot of interpreter state in
an opaque token returned by <B>Tcl_SaveInterpState</B>.  That token
value may then be passed back to one of <B>Tcl_RestoreInterpState</B>
or <B>Tcl_DiscardInterpState</B>, depending on whether the interp
state is to be restored.  So long as one of the latter two routines
is called, Tcl will take care of memory management.
<P>
The second triplet stores the snapshot of only the interpreter
result (not its complete state) in memory allocated by the caller.
These routines are passed a pointer to <B>Tcl_SavedResult</B>
that is used to store enough information to restore the interpreter result.
<B>Tcl_SavedResult</B> can be allocated on the stack of the calling
procedure.  These routines do not save the state of any error
information in the interpreter (e.g. the <B>-errorcode</B> or
<B>-errorinfo</B> return options, when an error is in progress).
<P>
Because the routines <B>Tcl_SaveInterpState</B>,
<B>Tcl_RestoreInterpState</B>, and <B>Tcl_DiscardInterpState</B> perform
a superset of the functions provided by the other routines,
any new code should only make use of the more powerful routines.
The older, weaker routines <B>Tcl_SaveResult</B>, <B>Tcl_RestoreResult</B>,
and <B>Tcl_DiscardResult</B> continue to exist only for the sake
of existing programs that may already be using them.
<P>
<B>Tcl_SaveInterpState</B> takes a snapshot of those portions of
interpreter state that make up the full result of script evaluation.
This include the interpreter result, the return code (passed in
as the <I>status</I> argument, and any return options, including
<B>-errorinfo</B> and <B>-errorcode</B> when an error is in progress.
This snapshot is returned as an opaque token of type <B>Tcl_InterpState</B>.
The call to <B>Tcl_SaveInterpState</B> does not itself change the
state of the interpreter.  Unlike <B>Tcl_SaveResult</B>, it does
not reset the interpreter.
<P>
<B>Tcl_RestoreInterpState</B> accepts a <B>Tcl_InterpState</B> token
previously returned by <B>Tcl_SaveInterpState</B> and restores the
state of the interp to the state held in that snapshot.  The return
value of <B>Tcl_RestoreInterpState</B> is the status value originally
passed to <B>Tcl_SaveInterpState</B> when the snapshot token was
created.
<P>
<B>Tcl_DiscardInterpState</B> is called to release a <B>Tcl_InterpState</B>
token previously returned by <B>Tcl_SaveInterpState</B> when that
snapshot is not to be restored to an interp.
<P>
The <B>Tcl_InterpState</B> token returned by <B>Tcl_SaveInterpState</B>
must eventually be passed to either <B>Tcl_RestoreInterpState</B>
or <B>Tcl_DiscardInterpState</B> to avoid a memory leak.  Once
the <B>Tcl_InterpState</B> token is passed to one of them, the
token is no longer valid and should not be used anymore.
<P>
<B>Tcl_SaveResult</B> moves the string and value results
of <I>interp</I> into the location specified by <I>statePtr</I>.
<B>Tcl_SaveResult</B> clears the result for <I>interp</I> and
leaves the result in its normal empty initialized state.
<P>
<B>Tcl_RestoreResult</B> moves the string and value results from
<I>statePtr</I> back into <I>interp</I>.  Any result or error that was
already in the interpreter will be cleared.  The <I>statePtr</I> is left
in an uninitialized state and cannot be used until another call to
<B>Tcl_SaveResult</B>.
<P>
<B>Tcl_DiscardResult</B> releases the saved interpreter state
stored at <B>statePtr</B>.  The state structure is left in an
uninitialized state and cannot be used until another call to
<B>Tcl_SaveResult</B>.
<P>
Once <B>Tcl_SaveResult</B> is called to save the interpreter
result, either <B>Tcl_RestoreResult</B> or
<B>Tcl_DiscardResult</B> must be called to properly clean up the
memory associated with the saved state.
<H3><A NAME="M6">KEYWORDS</A></H3>
<A href="../Keywords/R.htm#result">result</A>, <A href="../Keywords/S.htm#state">state</A>, <A href="../Keywords/I.htm#interp">interp</A>
<div class="copy">Copyright &copy; 1997 Sun Microsystems, Inc.
</div>
</BODY></HTML>
